HAL TAMP Functions

HAL TAMP passive tamper mode functions

STM32C562xx STM32C5A3xx STM32C542xx

group TAMP_Exported_Functions_Passive

In passive mode the tampers inputs are monitored and a tamper is detected either on edge or level detection. Those different detection types can be configured by changing the parameters of a digital filter that are common for all the passive tampers. This filter is used to avoid false tamper detection. The passive tampers can work in confirmed or potential modes.

Passive tampers

Edge detection

Edge mode consists of a tamper event generation when either a rising or falling edge is observed. To configure the tampers in edge mode, the application must call HAL_TAMP_PASSIVE_SetConfig with hal_tamp_passive_config_t::type_activation set to HAL_TAMP_PASSIVE_FILTER_DISABLE. The parameter hal_tamp_passive_individual_config_t::trigger must be set to the desired edge type by calling the HAL_TAMP_PASSIVE_SetConfigTampers.

The user can use this mode of tamper detection with the RTCCLK disabled.

Level detection

Level mode consists of a tamper event generation when two, four or eight consecutive samples are observed at the level configured. Calling the HAL_TAMP_PASSIVE_SetConfigTampers and setting hal_tamp_passive_individual_config_t::trigger enables the configuration of the level. To configure the tampers in level mode, the application must call HAL_TAMP_PASSIVE_SetConfig with hal_tamp_passive_config_t::type_activation set to:

• HAL_TAMP_PASSIVE_FILTER_2_SAMPLES, for two samples detection.

• HAL_TAMP_PASSIVE_FILTER_4_SAMPLES, for four samples detection.

• HAL_TAMP_PASSIVE_FILTER_8_SAMPLES, for eight samples detection.

The sampling frequency is chosen by programming the hal_tamp_passive_config_t::sample_frequency

The inputs can be precharged before being sampled for a certain duration. Configure this by calling HAL_TAMP_PASSIVE_SetConfig and programming the parameters hal_tamp_passive_config_t::precharge and hal_tamp_passive_config_t::precharge_duration

Potential and confirmed mode.

Each tamper can work in two modes regarding device secrets erase. The confirmed mode means that when a tamper event occurs, the device secrets are automatically erased. The potential mode does not erase all the device secrets when a tamper event occurs. Instead, it blocks read and write access to the device secrets. Access is unblocked when the tamper event is cleared. To configure the erase mode, call HAL_TAMP_PASSIVE_SetConfigTampers and configure the hal_tamp_passive_individual_config_t::erase_secrets parameter.

Masked

The tampers can be masked. This means that the application does not need to clear them after a trigger. If a tamper is masked, triggering the tamper event will not affect the device secrets in any way. This feature is only available when using passive tampers in level mode and interrupts are disabled.

Functions

hal_status_t HAL_TAMP_PASSIVE_SetConfig ( const hal_tamp_passive_config_t * p_config )

Configure the passive tampers global parameters.

Parameters :

p_config – Pointer to the passive tampers global configuration instance.

Return values :

HAL_OK – if the configuration is successful, HAL_INVALID_PARAM if the parameter is invalid.

void HAL_TAMP_PASSIVE_GetConfig ( hal_tamp_passive_config_t * p_config )

Retrieve the passive tamper global parameters.

Parameters :

p_config – Pointer to the passive tampers global configuration instance.

hal_status_t HAL_TAMP_PASSIVE_SetConfigTampers ( uint32_t tampers , const hal_tamp_passive_individual_config_t * p_config )

Configure the passive tampers individual parameters.

Parameters :

• tampers – tampers to be configured, can be a combination of

  • HAL_TAMP_TAMPER_1

  • HAL_TAMP_TAMPER_2

  • HAL_TAMP_TAMPER_3

• p_config – Pointer to the passive tamper individual configuration instance.

Return values :

HAL_OK, HAL_INVALID_PARAM – if the parameter is invalid

void HAL_TAMP_PASSIVE_GetConfigTamper ( uint32_t tamper , hal_tamp_passive_individual_config_t * p_config )

Retrieve the passive tamper individual parameters.

Parameters :

• tamper – tamper to retrieve the configuration, can be one of the following values

  • HAL_TAMP_TAMPER_1

  • HAL_TAMP_TAMPER_2

  • HAL_TAMP_TAMPER_3

• p_config – Pointer to the passive tamper individual configuration instance.

hal_status_t HAL_TAMP_PASSIVE_Start ( uint32_t tampers , uint32_t interruption )

Start the passive tampers.

Parameters :

• tampers – tampers to be started, can be a combination of

  • HAL_TAMP_TAMPER_1

  • HAL_TAMP_TAMPER_2

  • HAL_TAMP_TAMPER_3

• interruption – enable the interruption, can be a combination of

  • HAL_TAMP_IT_NONE

  • HAL_TAMP_IT_TAMPER_1

  • HAL_TAMP_IT_TAMPER_2

  • HAL_TAMP_IT_TAMPER_3

Return values :

• HAL_OK –

• HAL_ERROR – If trying to enable an interruption to a masked tamper.

hal_status_t HAL_TAMP_PASSIVE_Stop ( uint32_t tampers )

Stop the passive tampers.

Parameters :

tampers – tampers to be stopped, can be a combination of

• HAL_TAMP_TAMPER_1

• HAL_TAMP_TAMPER_2

• HAL_TAMP_TAMPER_3

Return values :

HAL_OK –

hal_status_t HAL_TAMP_PASSIVE_PollForEvent ( uint32_t tampers , uint32_t timeout_ms )

Poll for a tamper event among tampers given in tampers.

Note

Call HAL_TAMP_PASSIVE_Stop to clear the pending tamper event.

Parameters :

• tampers – tampers to be checked, can be a combination of

  • HAL_TAMP_TAMPER_1

  • HAL_TAMP_TAMPER_2

  • HAL_TAMP_TAMPER_3

• timeout_ms – Timeout duration

Return values :

• HAL_OK –

• HAL_TIMEOUT – when reaching the timeout during polling.

HAL TAMP internal tamper mode functions

STM32C562xx STM32C5A3xx STM32C542xx

group TAMP_Exported_Functions_Internal

The internal tampers are tampers linked to a specific part of the microcontroller. They protect the microcontroller device secrets in case of transient or environmental perturbation attacks. They can work in potential or confirmed mode.

Each tamper can work in two modes regarding the device secrets erase. The confirmed mode means that when a tamper event occurs, the device secrets are automatically erased. The potential mode does not erase all the device secrets when a tamper event occurs. Instead, it blocks read and write access to the device secrets. The access is unblocked when the tamper event is cleared.

To configure the erase mode, call HAL_TAMP_INTERNAL_SetConfigTampers and configure the hal_tamp_internal_individual_config_t::erase_secrets parameter.

Functions

hal_status_t HAL_TAMP_INTERNAL_SetConfigTampers ( uint32_t internal_tampers , const hal_tamp_internal_individual_config_t * p_config )

Configure the internal tampers individual parameters.

Parameters :

• internal_tampers – tampers to be configured, can be a combination of

  • HAL_TAMP_INTERNAL_TAMPER_3

  • HAL_TAMP_INTERNAL_TAMPER_4

  • HAL_TAMP_INTERNAL_TAMPER_5

  • HAL_TAMP_INTERNAL_TAMPER_6

  • HAL_TAMP_INTERNAL_TAMPER_9

  • HAL_TAMP_INTERNAL_TAMPER_11

• p_config – Pointer to the internal tamper individual configuration instance.

Return values :

HAL_OK –

void HAL_TAMP_INTERNAL_GetConfigTamper ( uint32_t internal_tamper , hal_tamp_internal_individual_config_t * p_config )

Retrieve the internal tamper individual parameter.

Parameters :

• internal_tamper – tamper to retrieve the configuration, can be one of the following values

  • HAL_TAMP_INTERNAL_TAMPER_3

  • HAL_TAMP_INTERNAL_TAMPER_4

  • HAL_TAMP_INTERNAL_TAMPER_5

  • HAL_TAMP_INTERNAL_TAMPER_6

  • HAL_TAMP_INTERNAL_TAMPER_9

  • HAL_TAMP_INTERNAL_TAMPER_11

• p_config – Pointer to the internal tamper individual configuration instance.

hal_status_t HAL_TAMP_INTERNAL_Start ( uint32_t internal_tampers , uint32_t interruption )

Start the internal tampers.

Parameters :

• internal_tampers – internal tampers to be started, can be a combination of

  • HAL_TAMP_INTERNAL_TAMPER_3

  • HAL_TAMP_INTERNAL_TAMPER_4

  • HAL_TAMP_INTERNAL_TAMPER_5

  • HAL_TAMP_INTERNAL_TAMPER_6

  • HAL_TAMP_INTERNAL_TAMPER_9

  • HAL_TAMP_INTERNAL_TAMPER_11

• interruption – enable the interruption, can be a combination of

  • HAL_TAMP_INTERNAL_IT_NONE

  • HAL_TAMP_INTERNAL_IT_TAMPER_3

  • HAL_TAMP_INTERNAL_IT_TAMPER_4

  • HAL_TAMP_INTERNAL_IT_TAMPER_5

  • HAL_TAMP_INTERNAL_IT_TAMPER_6

  • HAL_TAMP_INTERNAL_IT_TAMPER_9

  • HAL_TAMP_INTERNAL_IT_TAMPER_11

Return values :

HAL_OK –

hal_status_t HAL_TAMP_INTERNAL_Stop ( uint32_t internal_tampers )

Stop the internal tampers.

Parameters :

internal_tampers – tampers to be stopped, can be a combination of

• HAL_TAMP_INTERNAL_TAMPER_3

• HAL_TAMP_INTERNAL_TAMPER_4

• HAL_TAMP_INTERNAL_TAMPER_5

• HAL_TAMP_INTERNAL_TAMPER_6

• HAL_TAMP_INTERNAL_TAMPER_9

• HAL_TAMP_INTERNAL_TAMPER_11

Return values :

HAL_OK –

hal_status_t HAL_TAMP_INTERNAL_PollForEvent ( uint32_t internal_tampers , uint32_t timeout_ms )

Poll for a internal tamper event among internal tampers given in internal_tampers.

Note

Call HAL_TAMP_INTERNAL_Stop to clear the pending internal tamper event.

Parameters :

• internal_tampers – Internal tampers to be checked, can be a combination of

  • HAL_TAMP_INTERNAL_TAMPER_3

  • HAL_TAMP_INTERNAL_TAMPER_4

  • HAL_TAMP_INTERNAL_TAMPER_5

  • HAL_TAMP_INTERNAL_TAMPER_6

  • HAL_TAMP_INTERNAL_TAMPER_9

  • HAL_TAMP_INTERNAL_TAMPER_11

• timeout_ms – Timeout duration

Return values :

• HAL_OK –

• HAL_TIMEOUT – when reaching the timeout during polling.

HAL TAMP IRQ functions

STM32C562xx STM32C5A3xx STM32C542xx

group TAMP_Exported_Functions_IRQ

IRQ handler functions to manage the different tamper event interrupts.

Functions

void HAL_TAMP_IRQHandler ( void )

IRQ handler of the different tamper interrupts.

void HAL_TAMP_TamperIRQHandler ( void )

IRQ handler of the external tampers interrupts.

void HAL_TAMP_InternalTamperIRQHandler ( void )

IRQ handler of the internal tampers interrupts.

HAL TAMP callback functions

STM32C562xx STM32C5A3xx STM32C542xx

group TAMP_Exported_Functions_Callback

Callback functions that the user can overwrite for the different interrupts:

• Internal tampers.

• External tampers.

Functions

void HAL_TAMP_InternalTamperEventCallback ( uint32_t internal_tampers )

Internal tamper event callback.

Parameters :

internal_tampers – This parameter can be a combination of

• HAL_TAMP_INTERNAL_TAMPER_3

• HAL_TAMP_INTERNAL_TAMPER_4

• HAL_TAMP_INTERNAL_TAMPER_5

• HAL_TAMP_INTERNAL_TAMPER_6

• HAL_TAMP_INTERNAL_TAMPER_9

• HAL_TAMP_INTERNAL_TAMPER_11

void HAL_TAMP_TamperEventCallback ( uint32_t tampers )

External tamper event callback.

Parameters :

tampers – This parameter can be a combination of

• HAL_TAMP_TAMPER_1

• HAL_TAMP_TAMPER_2

• HAL_TAMP_TAMPER_3

HAL TAMP device secrets functions

STM32C562xx STM32C5A3xx STM32C542xx

group TAMP_Exported_Functions_Device_Secrets

The device secrets consist of different resources of the microcontroller

Backup registers

There are 32 backup registers. The backup registers are registers that the application can write anything it wants by calling HAL_TAMP_WriteBackupRegisterValue.

Device secrets access and erase.

The application can enable and disable the access of the different device secrets by calling HAL_TAMP_UnblockDeviceSecretsAccess and HAL_TAMP_BlockDeviceSecretsAccess respectively. By default they can be accessed.

The application can also manually erase the different device secrets by calling the HAL_TAMP_EraseDeviceSecrets function.

Functions

hal_status_t HAL_TAMP_WriteBackupRegisterValue ( hal_tamp_backup_register_idx_t backup_register_index , uint32_t data_32bit )

Program the value of the backup register given by the parameter backup_register_index.

Parameters :

• backup_register_index – Index of the backup register.

• data_32bit – Value to be programmed.

Return values :

HAL_OK –

uint32_t HAL_TAMP_ReadBackupRegisterValue ( hal_tamp_backup_register_idx_t backup_register_index )

Retrieve the value of the backup register given by the parameter backup_register_index.

Parameters :

backup_register_index – Index of the backup register.

Return values :

uint32_t – Value of the backup register

hal_status_t HAL_TAMP_UnblockDeviceSecretsAccess ( void )

Unblock access to the backup registers and device secrets.

Return values :

HAL_OK –

hal_status_t HAL_TAMP_BlockDeviceSecretsAccess ( void )

Block access to the backup registers and device secrets.

Return values :

HAL_OK –

hal_tamp_secrets_status_t HAL_TAMP_IsBlockedDeviceSecretsAccess ( void )

Check if the access to the device secrets is blocked.

Return values :

hal_tamp_secrets_status_t – Device secrets access status.

hal_status_t HAL_TAMP_EraseDeviceSecrets ( void )

Erase the backup registers and device secrets.

Return values :

HAL_OK –

HAL TAMP remap functions

STM32C562xx STM32C5A3xx STM32C542xx

group TAMP_Exported_Functions_Remap

This section provides functions allowing to manage the Tamp remap pin features:

• Call HAL_TAMP_EnableRemap() to enable TAMP pin remap.

• Call HAL_TAMP_DisableRemap() to disable TAMP pin remap.

• Call HAL_TAMP_IsEnabledRemap() to check that the selected TAMP pin is remapped or not.

Functions

void HAL_TAMP_EnableRemap ( uint32_t tamp_remap )

Enable remap of TAMP INx / OUTx on different pin(s).

Parameters :

tamp_remap – Specifies tamp pins to remap, can be a combination of

• HAL_TAMP_REMAP_TAMP_IN2_PA0_TO_PC1

• HAL_TAMP_REMAP_TAMP_IN3_PA1_TO_PA2

void HAL_TAMP_DisableRemap ( uint32_t tamp_remap )

Disable remap of TAMP INx / OUTx on different pin(s).

Parameters :

tamp_remap – Specifies tamp pins to disable remap, can be a combination of

• HAL_TAMP_REMAP_TAMP_IN2_PA0_TO_PC1

• HAL_TAMP_REMAP_TAMP_IN3_PA1_TO_PA2

hal_tamp_remap_status_t HAL_TAMP_IsEnabledRemap ( uint32_t tamp_remap )

Check if remap TAMP INx / OUTx is enabled or disabled.

Parameters :

tamp_remap – Specifies tamp pins to get the remap status, can be a value of

• HAL_TAMP_REMAP_TAMP_IN2_PA0_TO_PC1

• HAL_TAMP_REMAP_TAMP_IN3_PA1_TO_PA2

Return values :

hal_tamp_remap_status_t – Tamp remap status.

management functions

STM32C562xx STM32C5A3xx STM32C542xx

group TAMP_Exported_Functions_Attributes

This section provides functions for managing security, privilege configurations:

• Call HAL_TAMP_SetPrivAttr() to set the privilege attribute of specified TAMP item(s).

• Call HAL_TAMP_GetPrivAttr() to get the privilege attribute state of specified TAMP item.

Functions

hal_status_t HAL_TAMP_SetPrivAttr ( uint32_t item , hal_tamp_priv_attr_t priv_attr )

Set TAMP item(s) privilege configuration.

Parameters :

• item – This parameter can be one of the following values:

  • HAL_TAMP_PRIV_ITEM_TAMP

  • HAL_TAMP_PRIV_ITEM_BACKUP_ZONE_1

  • HAL_TAMP_PRIV_ITEM_BACKUP_ZONE_2

• priv_attr – This parameter is an element of hal_tamp_priv_attr_t enumeration.

Return values :

• HAL_ERROR – Non-Privileged write to a privilege-only register.

• HAL_OK – Privilege has been correctly configured.

hal_tamp_priv_attr_t HAL_TAMP_GetPrivAttr ( uint32_t item )

Get TAMP item privilege configuration.

Parameters :

item – This parameter can be one of the following values:

• HAL_TAMP_PRIV_ITEM_TAMP

• HAL_TAMP_PRIV_ITEM_BACKUP_ZONE_1

• HAL_TAMP_PRIV_ITEM_BACKUP_ZONE_2

Return values :

Returned – value is an element of hal_tamp_priv_attr_t enumeration.

hal_status_t HAL_TAMP_SetBackupRegisterZones ( uint32_t zone1_backup_register_nbr , uint32_t zone2_backup_register_nbr )

Configure the protection boundaries for backup register zones.

Parameters :

• zone1_backup_register_nbr – Last valid backup register index for Backup Register Zone 1. Value from 0 to 32.

• zone2_backup_register_nbr – Last valid backup register index for Backup Register Zone 2. Value from 0 to 32.

Return values :

HAL_OK – Backup register zones have been set successfully.

hal_status_t HAL_TAMP_GetBackupRegisterZones ( uint32_t * p_zone1_backup_register_nbr , uint32_t * p_zone2_backup_register_nbr )

Retrieve backup register zones protection boundaries.

Parameters :

• p_zone1_backup_register_nbr – Pointer to a variable that will receive the last valid backup register index of Backup Register Zone 1. Returned value is from 0 to 32.

• p_zone2_backup_register_nbr – Pointer to a variable that will receive the last valid backup register index of Backup Register Zone 2. Returned value is from 0 to 32.

Return values :

• HAL_OK – Backup register zones boundaries have been retrieved successfully.

• HAL_INVALID_PARAM – Parameter value is NULL.

TAMP_Exported_Functions_For_Backup_Zone

STM32C562xx STM32C5A3xx STM32C542xx

group TAMP_Exported_Functions_For_Backup_Zone

This section provides functions to manage backup register zones and their privilege configuration. The backup register zone boundaries can be configured and retrieved using:

• HAL_TAMP_SetBackupRegisterZones() to configure the end index of Backup Register Zone 1 and Zone 2.

• HAL_TAMP_GetBackupRegisterZones() to get the last valid index of Backup Register Zone 1 and Zone 2.

Functions

hal_status_t HAL_TAMP_SetBackupRegisterZones ( uint32_t zone1_backup_register_nbr , uint32_t zone2_backup_register_nbr )

Configure the protection boundaries for backup register zones.

Parameters :

• zone1_backup_register_nbr – Last valid backup register index for Backup Register Zone 1. Value from 0 to 32.

• zone2_backup_register_nbr – Last valid backup register index for Backup Register Zone 2. Value from 0 to 32.

Return values :

HAL_OK – Backup register zones have been set successfully.

hal_status_t HAL_TAMP_GetBackupRegisterZones ( uint32_t * p_zone1_backup_register_nbr , uint32_t * p_zone2_backup_register_nbr )

Retrieve backup register zones protection boundaries.

Parameters :

• p_zone1_backup_register_nbr – Pointer to a variable that will receive the last valid backup register index of Backup Register Zone 1. Returned value is from 0 to 32.

• p_zone2_backup_register_nbr – Pointer to a variable that will receive the last valid backup register index of Backup Register Zone 2. Returned value is from 0 to 32.

Return values :

• HAL_OK – Backup register zones boundaries have been retrieved successfully.

• HAL_INVALID_PARAM – Parameter value is NULL.